昨天發佈了 Sinopac PHP SDK,接著來有幾天的篇幅會介紹如何使用。今天先來談談建立訂單的部分。
在 Day 11 我們已經實例化 QPay
類別。
圖 12-1: PHP SDK - 實例化 QPay 類別 程式碼
接著可以使用以下方法來建立訂單。
和 API 的欄位稍有不同,陣列的鍵值一律小寫 Snake-case naming,是為了一致的 Coding Style 及簡化輸入架構,一律為一維陣列。
有的必填參數已自動帶入了所以不用填寫,只列出對應的部分。
array
$data)建立信用卡訂單,使用信用卡刷卡付款。
資料欄位 | 對應 API 的欄位 | 說明 |
---|---|---|
order_no * |
OrderNo | 訂單編號 |
amount * |
Amount | 訂單總金額,需補上小數二位,若金額為 10 元則值請填入 1000 |
product_name * |
PrdtName | 商品名稱 |
order_note | Memo | 備註 |
param_1 | Param1 | 自訂參數一 |
param_2 | Param2 | 自訂參數二 |
param_3 | Param3 | 自訂參數三 |
return_url * |
ReturnURL | 將消費者端導回您指定的付款完成頁面 |
backend_url | BackendURL | 通知您主機端付款完成的 URL |
cc_auto_billing * |
CardParam [AutoBilling] | 建立信用卡時為 - Y :自動請款 N :不自動請款。若使用銀聯卡或定期定額時系統一律為自動請款。 |
cc_expired_billing_days | CardParam [ExpBillingDays] | 若訂單為待授權未請款時,可以指定刷卡完成後多久自動請款。可設定範圍為 1-7 但是 AutoBilling 設為 Y 時則該參數會忽略。 |
cc_expired_minutes | CardParam [ExpMinutes] | 信用卡付款連結有效時間(分鐘) 。預設為 10 分鐘可設定範圍為 1-30 |
程式碼範例:
圖 12-2: PHP SDK - 建立信用卡訂單 程式碼
以上為使用 createOrderByCreditCard 方法建立訂單,API 回應的結果主要資訊在 Message
已解密為陣列結構,請參考 API 文件第 35 頁,有對回應的欄位有詳細說明。
array
$data)建立虛擬帳號訂單,使用 ATM 轉帳到虛擬帳號付款。
資料欄位 | 對應 API 的欄位 | 說明 |
---|---|---|
order_no * |
OrderNo | 訂單編號 |
amount * |
Amount | 訂單總金額,需補上小數二位,若金額為 10 元則值請填入 1000 |
product_name * |
PrdtName | 商品名稱 |
order_note | Memo | 備註 |
param_1 | Param1 | 自訂參數一 |
param_2 | Param2 | 自訂參數二 |
param_3 | Param3 | 自訂參數三 |
return_url * |
ReturnURL | 將消費者端導回您指定的付款完成頁面 |
backend_url | BackendURL | 通知您主機端付款完成的 URL |
atm_expired_date * |
ATMParam [ExpireDate] | 付款截止日期。例如 2017/5/3 則帶 20170503,設定值最大為 30 天。 |
程式碼範例:
圖 12-3: PHP SDK - 建立虛擬帳號訂單 程式碼
以上為使用 createOrderByATM 方法建立訂單,API 回應的結果主要資訊在 Message
已解密為陣列結構,請參考 API 文件第 35 頁,有對回應的欄位有詳細說明。
在前一個文章段落介紹的建單過程取得永豐金收款平台的 API 回應後,資料欄位在 Message
且 SDK 已自動解密可直接取用。
<?php
if (!empty($results['Message'])) {
print_r($results['Message']);
}
圖 12-4: 信用卡訂單 Messsage 欄位 (JSON 排版)
建立信用卡訂單後,API 的回應會有 CardPayURL
這個欄位,提供給商店網站進行轉址到信用卡付款頁面,讓使用者進行付款。付款完再跳轉回商店網站,如下圖流程。
圖 12-5: 文件第 7 頁
在永豐金收款平台刷卡完之後,從建立訂單的欄位 return_url
轉回商店網站時會帶上 PayToken 參數,讓商店網站可以查詢付款狀態。
圖 12-6: 虛擬帳號訂單 Messsage 欄位 (JSON 排版)
建立虛擬帳號訂單後,API 的回應會,API 的回應會有 AtmPayNo
、WebAtmURL
、OtpURL
這三個欄位,提供給商店網站。
圖 12-7: 文件第 6 頁
AtmPayNo
用於顯示在結帳完成頁面 (Thank-you page) 或訂單資訊頁面,讓使用者能透過 ATM 轉帳進行結帳。
建立虛擬帳號訂單時,建議帶上 backend_url
,以利永豐金收款平台在收到款項時,即時通知商店網站進行商店的訂單狀態變更及其它商業邏輯上的後續處理(例如出貨,等等。)
PHP SDK 把中間複雜的 HashId 計算、IV 計算、Sign 計算、AES 加密、解密等流程,都幫忙處理了,所以只要用少少的程式碼就能完成串接,能大幅增加開發人員的工作效率喔。
如果在使用上有什麼問題,歡迎到 GitHub 回報,我會盡快修復唷。^^
註:如果是在測試環境,請記得啟用沙盒模式,發起 API 請求時會送往收款平台的測試網址。
$qpay->enableSandbox();
本文更新於筆者的 TerryL 部落格,Day 12 - PHP SDK: 建立信用卡、虛擬帳號訂單,有興趣可前往閱讀及討論。